home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource5 / 315_01 / fft.txt < prev    next >
Encoding:
Text File  |  1990-05-16  |  7.4 KB  |  167 lines
  1. DOCUMENTATION FOR FFT.C
  2.  
  3. Documentation dated 10/89.
  4. Program and documentation Copyright (c) 1989, E.R.I.  All rights reserved.
  5.  
  6. INTRODUCTION
  7.      FFT.C is the source file for supporting common FFT operations.  All FFT
  8. operations in FFT.C use double-precision floating-point data.  FFT.C was
  9. compiled under Microsoft C, v. 5.1, using the emulation library.  Thus, it will
  10. use a math coprocessor if one is installed on the computer, but does not require
  11. it.  As with all my compilations, the /Od flag was set, disabling optimization.
  12.      FFT.C includes one function that reads data files (data_multiply()).  The
  13. data format used in data_multiply() files is:
  14. A B C
  15. data
  16. data
  17. data;
  18. where A is the number of data points in the file, B is the minimum value of the
  19. data set, and C is the maximum value in the data set.  Each data point must be
  20. separated by white space, which can but does not have to include a carriage
  21. return.  The data files must be text format, not binary.
  22.      FFT.C makes explicit calls to functions in MENU.C and MOUSELIB.C.  MENU.C
  23. is part of FTPLOT.LIB, and MOUSELIB.C forms a separate library, MOUSELIB.LIB.
  24.  
  25. EXTERNALLY-VISIBLE FUNCTIONS IN FFT.C
  26.      The FFT.C functions are declared in FFT.H, which should be included in any
  27. program that utilizes these routines.
  28.  
  29. FUNCTION: data_multiply()
  30. TYPE: void
  31. ARGUMENTS: Two character strings
  32.  
  33.      data_multiply(file1, file2) multiplies the data in file1 by the data in
  34. file2, and outputs the result to a file that the user specifies in response to a
  35. prompt.  The format for each of these files is that explained above.
  36.  
  37.  
  38.  
  39. FUNCTION: dbl_scale()
  40. TYPE: int
  41. ARGUMENTS: three doubles and two ints
  42.  
  43.      i=dbl_scale(val,min,max,out_min,out_max) scales a double-precision number
  44. VAL, that can range from MIN to MAX into an int. The output int can range from
  45. OUT_MIN to OUT_MAX. dbl_scale() is used to scale a double-precision number for
  46. graphing.  Notice that you can make OUT_MIN larger than OUT_MAX if you want to
  47. invert the scale for screen display -- that is, most computer screens have 
  48. large Y values at the BOTTOM and small values at the top.  By making OUT_MIN
  49. the largest screen y-value and OUT_MAX the smallest, the routine will auto-
  50. scale with inversion.
  51.  
  52.  
  53. FUNCTION: fft()
  54. TYPE: void
  55. ARGUMENTS: two arrays of doubles and two ints.
  56.  
  57.      fft(x,y,n,flag) accepts the n data points x[i], y[i] and transforms them to
  58. the other domain.  n must be an even power of 2, and cannot exceed 4096.  If
  59. flag is -1, then x and y are time-domain data points (x=real, y is normally an
  60. array of 0s). If flag is 1, then x and y are frequency-domain data points
  61. (rectangular coordinates, x=real, y=imaginary).  The routine is an in-place
  62. algorithm, which means that the result of the fft is returned in the x and y
  63. arrays.  The fft routine does not normalize forward (time to frequency)
  64. transforms.  Rather, it waits until the inverse transform to normalize.  If you
  65. perform a forward and then an inverse transform, you will end up with the
  66. original data (within round-off error).  However, if you only perform forward
  67. transforms, the data will be weighted by the number of data points in the
  68. transform.  For example, if you do a 256-point fft of a 1 Hz sine wave, and a
  69. 512-point fft of the same 1 Hz sine wave, the unnormalized data will make the
  70. amplitude of the 512-point transform appear to be twice as large as the 256-
  71. point transform.  If you are only comparing transforms with the same number of
  72. data points, the failure to normalize does not matter in either domain.
  73. However, if you will be comparing different size transforms, you should
  74. normalize the results by dividing each transformed data point by the number of
  75. points in the data set.
  76.  
  77.  
  78.  
  79. FUNCTION: get_filter()
  80. TYPE: pointer to double
  81. ARGUMENTS: one array of doubles, two ints, and four doubles.
  82.  
  83.      fptr = get_filter(filter, n, direction, nyquist, cutoff, rolloff, units)
  84. builds a high-pass or low-pass filter, and returns a pointer to the array of
  85. frequency-domain filter coefficients (fptr).  filter is the array that the
  86. coefficients will be written into, so fptr = &filter[0].  n is the number of
  87. points in the filter.  direction = 1 specifies that the filter is high-pass, and
  88. direction = -1 specifies that the filter is low-pass.  nyquist is the maximum
  89. defined frequency in the filter data set.  cutoff is the cutoff frequency of the
  90. filter, rolloff is the rolloff in either dB per octave or dB per decade,
  91. depending on the value of units (2.0 or 10.0).  get_filter() only produces
  92. positive/negative format amplitude data.  If you want positive-only data, throw
  93. away the last n/2 data points.  The filter generated by get_filter() is used by
  94. multiplying an amplitude spectrum by filter.  If you save filter as a file in
  95. the format given in this document's introduction, you can use data_multiply() on
  96. the amplitude part of polar-format frequency data to perform the filtering.
  97.  
  98.  
  99.  
  100. FUNCTION: int_scale()
  101. TYPE: int
  102. ARGUMENTS: five ints.
  103.  
  104.      i=int_scale(val,min,max,out_min,out_max) is the integer-input version of
  105. dbl_scale().  See that function for details.    
  106.  
  107.  
  108.  
  109. FUNCTION: long_scale()
  110. TYPE: int
  111. ARGUMENTS: three long ints and two ints.
  112.  
  113.      i=long_scale(val,min,max,out_min,out_max) is the long int version of
  114. dbl_scale().  See that function for details.
  115.  
  116.  
  117.  
  118. FUNCTION: minmax()
  119. TYPE: void
  120. ARGUMENTS: one array of doubles, one int, and two pointers to doubles
  121.  
  122.      minmax(array, n, minv, maxv) finds the minimum and maximum value in the n
  123. data points in array, and writes those values into the locations specified by
  124. minv and maxv.  This is useful in generating the data for the file format
  125. specified in the introduction.
  126.  
  127.  
  128.  
  129. FUNCTION: polar_to_xy()
  130. TYPE: void
  131. ARGUMENTS: four arrays of doubles and one int.
  132.  
  133.      polar_to_xy(amp, phase, x, y, n) converts the n polar-format data points in
  134. amp, phase to rectangular-format data in x, y.  amp,phase and x,y can be the
  135. same arrays if you want to overwrite the current data, i,e,,
  136. polar_to_xy(x,y,x,y,n) a valid call.  The data arrays in fft() are assumed to be
  137. x, y format.
  138.  
  139.  
  140.  
  141. FUNCTION: unscramble_transform()
  142. TYPE: void
  143. ARGUMENTS: one array of doubles and one int.
  144.  
  145.      unscramble_transform(array, n) takes the positive/negative format frequency
  146. data array array and places the negative frequency components at the beginning
  147. of the array, so the x-axis of the graph is continuous.  When you perform a
  148. forward fft, the data array is ordered as follows: freq 0, freq 1, freq 2,
  149. ...freq nyquist, [the negative freq one less than the nyquist freq, the negative
  150. freq 2 less than the nyquist freq], etc.  I unscramble the array by moving freq
  151. 0 up to BUT NOT INCLUDING freq nyquist to the end of the array.  The x-axis thus
  152. runs from -freq nyquist to +freq (nyquist-1), in order.  The reason that I don't
  153. move the Nyquist frequency is that two successive calls to this function will
  154. return the array to its original order (which you must do before performing an
  155. inverse transform on the data set).
  156.  
  157.  
  158.  
  159. FUNCTION: xy_to_polar()
  160. TYPE: void
  161. ARGUMENTS: four arrays of doubles and an int.
  162.  
  163.      xy_to_polar(x, y, amp, phase, n) converts the n data points in rectangular-
  164. format frequency arrays x and y to polar-format data arrays amp and phase.  If
  165. you do not want to preserve the original format data, you can use the same data
  166. names for x and amp and y and phase, i.e., xy_to_polar(x, y, x, y, n) is a legal
  167. call.